MacFormat 1995 January/macformat-020.iso/Shareware City/Newton/slurpee-11/mac/Slurpee.txt

Text File | 1994-10-01 | 11.8 KB | 297 lines | [TEXT/R*ch]

Slurpee.txt
9/3/94

Slurpee 1.1
transfers paragraphs or tab-delimited text
between a text file and Newton soup entries
via a terminal emulator and serial connection

see Slurpee.1st for other info.


=====
Why?

I wanted a convenient way to move information from the desktop to soups on the
Newton, especially text paragraphs to separate Notepad entries, and vice
versa.  Newton Connection Kit (NCK) is also a possibility, though it is
slower, more complicated, and expensive.  Although Slurpee was created
primarily to support moving NewtonScript application/method sources by users
of my Newt application development tool, I thought that this utility may be
useful for others as well.


=====
Slurp and Slurpee -- Introduction and Differences

Slurpee is a customized version of the Apple DTS "Slurp-3" example -- with
thanks to the original author Scott (Zz) Zimmerman. The original Slurp
documentation and examples are included as SlurpOld.txt and CasioNam.tab. I
did not include the Slurp NTK project source files -- these can be obtained
from AppleLink and ftp.apple.com (Slurp may have been superceded by the
SuperSlurp example).

Slurp: Copyright 1993, 1994, Apple Computer, All Rights Reserved.
Slurpee modifications: Copyright 1994, S. Weyer

Slurpee is freeware (especially since so much of it is based on Slurp). Slurpee
may be freely distributed via online services and bulletin boards if it is
unmodified and includes this and other files mentioned here.  It may not be
commercially bundled or redistributed on CD-ROM, floppy disk, PCMCIA, networks
or other media without permission.

With enough encouragement, I may fix problems and add additional features. Of
course, you can also start with the original Slurp and roll your own version.
If Slurpee is useful to you, you can send email or a postcard, or better yet,
you can express your appreciation by registering for "Newt". Newt is a
shareware native Newton application development environment, i.e., you can
build applications in NewtonScript on your Newton.  In particular, I distribute
Newt source for Slurpee if you would like to make your own version or understand
how it works. More info at end of this file.

The original Slurp is one-way: it transmits lines in a desktop tab-delimited
text file sent over a serial connection into Newton soup entries. Slurpee is
two-way: it can also send Newton soup entries as a tab-delimited text file.
(This combines functionality you'd find in the DTS SerialPro example and the
freeware Pour utility).  Slurpee also works both ways in converting between
multiline text paragraphs and entries in the Notes soup.  I think I've fixed a
few Slurp problems with disconnecting cleanly.  I also added a "para" datatype
that's useful for adding a note to a Names entry, and a general "class:string"
datatype.

The original minimalist Slurp interface has changed only in the title, and some
additional status messages.  What's transferred and in which format is
controlled on the desktop side. For example, to send data to your Newton, you
tell Slurpee to Receive, and then send text containing soup name, format
specification, and data, via your terminal emulator, usually as a file.  To
send data from your Newton, you also set Slurpee to Receive; however, the text
file you send contains a soup name and format specification, but no data --
just a Dump command (this assumes you set up a log file to capture the data
returned).  Directions on how to setup Slurp/Slurpee with a terminal emulator
can be found in the original SlurpOld.txt and later in this file.

Slurpee 1.1 starts the connection automatically, and does not disconnect
automatically -- in other words, you never need to tap "Receive" unless you've
tapped "Disconnect".  Slurpee starts waiting immediately; after receiving each
file, it beeps and waits for the next.  Note: if you have many (or long)
transfers, you may wish to increase the Preferences:Sleep number so that your
Newton does not go to sleep during a transfer and lose data. (I may allow you
to change this in next version of Slurpee).

WARNING: since Slurpee can add or remove entries from your soups, please keep
your information backed up, and follow the formats and commands carefully.

=====
Slurpee Uses

Here is a summary of the four kinds of transfer supported by Slurpee:
      direction                         soup
----------------------      -------------------------
from desktop to Newton      1. any soup      2. Notes
from Newton to desktop      3. any soup      4. Notes

=====
1. the original Slurp ("Slurp classic")
first line    soup name, e.g., Names
second line   frame specification, e.g., see SlurpOld.txt and CasioNam.tab
other lines   each tab-delimited line corresponds to an entry
last line     BYE!

note: this only works with existing soups. Slurp/Slurpee does not create new
soups (currently).

For Names, I've found that a phones field is required, otherwise the entries
will generate errors later when you browse them.  At a minimum, you need
something like phones: ["workPhone"] in your framespec, then an extra tab in
your data entries to reflect an empty field.

If you'd like to add a text note to a Names entry (the text field you see when
you Show:Card&Notes), include notes: ["para"] in the frame spec. In the data
entries, the text in this position up to the next tab (or end of line if it's
last) will be included as a single paragraph in the note field.

Version 1.1 adds support for "class:string" type for entrySpec so you can embed
'class' information for strings directly with the value. For a phone entry,
you could specify "homePhone:555 1234" for input; you would also get this
format if you DUMP!

=====
2. Slurp for Notes
first line    Notes
second line   frame specification, e.g.,
  {labels: 'Business, viewFont: <fontspec>, height: <num>}**
line1 text
line2 more text
-----         paragraph delimiter (at least 5 dashes)
more lines
-----
BYE!

**the frame specification in 1) is more of a template with type information;
for Notes, it is used to provide default values.  For labels, the value is a
symbol corresponding to a folder destination, e.g., 'Personal, 'Business, or
nil or 'nil (for Unfiled).

If viewFont is not specified, then the Note (for the Notepad) is created with
the current default font set by the user in Styles. If viewFont is specified,
it should be a font specification, e.g., a coded integer like 10241
(userFont10) or font description like {family: 'espy, face: 0, size: 9} -- see
Newt or NTK documentation.  I have included viewFont: 10241 in the .nwt files
to be consistent with Newt's default.

If height is not specified, then Slurpee creates each Notepad entry with its
calculated height (in version 1.0, each had a fixed height of 265 -- which was
too large for some paragraphs, too short for others).  You can specify a fixed
height, e.g., {labels: 'Personal, height: 100}. If the Notepad clips a long
para, hold down on the note separator bar in the NotePad for several seconds,
then drag it downwards (it disappears) & then let go -- the separator should
jump to the end.

Note: if you include a symbol for labels slot that does not (yet) exist, be sure
to do Edit Folders later on your Newton to add it -- otherwise, the only
way you'll see these entries is via All Notes.

examples:

{labels: 'Business, viewFont: 10241} // what Newt normally uses
{labels: 'Personal} // uses current default font (Styles)
{labels: nil, viewFont: {family: 'espy, face: 0, size: 9}, height: 500}
{} // Unfiled folder with default font and calculated height
{labels: nil}  // same as {}
{labels: 'nil} // same as {}


Erase command:  if you know what you are doing (and have backed things up
first), you can insert an ERASE! command as the third line for 1&2.  This
erases all entries from the specified soup, or if you've specified labels in
your frame spec (for Names or Notes), it erases just the entries in that
folder.  This can be handy especially if want to get rid of many existing
entries before adding new information.  Warning: this does not give you a
dialog box asking to Confirm erasing of entries!!!  For example, if you edited
Newt sources for your project on the desktop, and wanted to replace these
completely on your Newton, you could do something like:

Notes
{labels: 'Programming, viewFont: 10241}
ERASE!
createApp
func()
...
-----
addFields
func()
....
-----
BYE!


=====
3. Slurp in reverse
first line    soup name, e.g., Names
second line   frame specification, e.g., CasioNam.dmp
DUMP!

same powerful frame specification as in 1). entries are written to terminal
emulator as tab-delimited lines in frame specification order.  To have Slurpee
pause so that you can set up a log/capture file, include the number of seconds
followed by a semi-colon, e.g., DUMP!10; .  Any data fields with text values
that contain newlines will be transmitted as is (you may need to re-edit
results into a true tab-delimited text format).

=====
4. Slurp for Notes, in reverse
first line    Notes
second line   frame specification, e.g., {labels: 'Business}**
DUMP!

**this is used as a filter to copy entries from only that folder. it copies all
text data entries from each Note (if it is non-empty text) as a paragraph. for
example, see Business.dmp. entries are written as multi-line entries separated
by -----.  see 3 for description of optional pause.


=====
How to Use (see SlurpOld.txt for further info):

- Download Slurpee to your Newton.

- Serial cable (still) connected to the Newton, with no other open serial
  connections on the desktop side (e.g., NTK inspector), or any other
  current use of comms on the Newton (e.g., beaming).

- Open a communications program (e.g., terminal emulator) on your desktop
  system, with the following specs:
    Serial Tool, 9600 baud, 8 data bits, 1 stop bit, XON/XOFF handshaking

  - For file transfer, specify the Text Tool.

- Open Slurpee; it is automatically starts in Receive mode. Or, if you have
  tapped Disconnect, then tap Receive.

- On the Mac/PC, choose "Send File..." in the comm program, and choose the
  file to be sent.  If you are doing a "Dump", immediately setup a file to
  log/receive/capture the result.  Slurpee will display the number of entries
  received/dumped in a view near the top of the screen.  When the file
  transfer is complete, Slurpee will automatically wait for another transfer.

- Tap Disconnect to end the connection, or just Quit.


=====
Slurpee Change History

1.1 (9/3/94)
-----
see Slurpee.1st

1.0 (6/6/94)
-----
- initial public release
- added 10 second delay after a DUMP! to allow time to log/receive/capture a file
- added an ERASE! command to clear out all soup entries or just those in a folder
- added a "para" datatype (useful for adding a note to a Names card)
- disconnects more cleanly

0.1
-----
- alpha/beta releases to Newt users


=====
Author

Stephen Weyer
17 Timber Knoll Drive
Washington Crossing, PA 18977-1052
Internet: [e-mail]
America Online/eWorld/NewtonMail: SteveWeyer
Compuserve: 74603,2051
AppleLink: WEYER.S


=====
Info about Newt

Newt 2.3:
a native development environment for simple applications using NewtonScript,
and for creating graphics using gestures, buttons, and NS.

Keywords: object-oriented programming, application development environment,
NewtonScript, NTK, learning, graphics, mathematics, Logo.

Where to usually find Newt [newt-devenv-23.sit / .hqx]:
- internet (also see mirror sites):
  - newton.uiowa.edu:pub/newton/software/app/ or /dev
  - sumex-aim.stanford.edu:info-mac/nwt/app/
  - ftp.amug.org:pub/newton
- newsgroups: comp.binaries.newton
- America Online(AOL): PDA:New Files (or PDA:Software Libraries:Newton)
- Compuserve: GO NEWTON (DL 8 or 9)
- AppleLink: Newton:Newton User Discussions:Freeware, Shareware and Demos
- eWorld: Shareware:Newton

Newt is shareware ($35) -- registered users receive a manual describing Newt
features and NewtonScript syntax, along with a floppy of other packages and
source examples -- of particular interest may be the Slurpee application
source itself in Slurpee format for Newt.